home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-11
/
ezhelp10.zip
/
EZHELP.TXT
< prev
next >
Wrap
Text File
|
1993-01-04
|
27KB
|
762 lines
EZhelp Reference
EZhelp# support functions for EZhelp Reference
EZcomp pop-up help system compiler
(C) Copyright 1990, Brain Child Systems.
All rights reserved.
--------------------------------------------------------------------------
{{ What's EZhelp?, 1,1,0 }}
........................................................................
I N T R O D U C T I O N
T O
E Z h e l p R e f e r e n c e
version 1.0
A ShareWare reference tool
(C) Copyright Brain Child Systems, 1990
All rights reserved
........................................................................
Hello!
EZhelp is a shareware product designed as a tool for writers or
programmers who need a simple help system to use stand-alone or
link with with existing software, or use as an on-line reference.
You can easily create a window driven help system with new or
existing texts, and registered users may distribute them with EZhelp
free of charge.
This reference guide is driven by EZhelp, and describes how to
set up your own text files and for in-house use or distribution.
Take a moment to read the help topics and move through the
different menus.
Any suggestions you have for the program are welcome. There are
many possible features that could be added, and this will depend on
what you ask for. If you try the program and have an opinion, drop
us a line!
EZhelp consists of three programs:
EZcomp.EXE - A text compiler program that creates
an index on help reference files you have
created. This index file describes where topics
begin and end within the text.
EZhelp.EXE - The program using the help file and the index
created with the compiler to drive the windows
and text display.
Showcolo.EXE - A utility to display colors and their values, to
assist in choosing colors for menus and windows.
You will need a text editor or word processor to create your text
files with. There are a few issues to be aware of when using a word
processor. For more information, select the "Entering text" menu.
You will also be more successful with this package if you follow
the hints on organizing your topics. More information can be found
in the "Forming Outline" menu.
EZhelp features:
choice of colors optional sorting of topics
pop-up menus choice of line style
fast display reference report
sizeable text window flexible use
start at any menu level low-cost updates
jump directly to any help topic
{{ 3 easy steps, 1,2,0 }}
3 easy steps
There are 3 steps to setting up your own help reference system:
1) Writing the reference help text -
Forming an outline, creating topic definitions,
and entering the text
2) Compiling text -
Compiling the text using EZcomp to create the
text index
3) Using EZhelp -
Calling the program with a choice of startup options
{{ Writing text, 1,3,2 }}
.... menu 2 is next ....
{{ Compiling text, 1,4,3 }}
.... menu 3 is next ....
{{ Using EZhelp, 1,5,4 }}
.... menu 4 is next ....
{{ Registering, 1,6,0 }}
Registering EZhelp
EZhelp is a shareware product, and may be used for a reasonable
trial period free of charge. What defines a reasonable trial period?
You may evaluate the package for 30 days, which should be enough
time to decide if you would like to continue using it.
The basic registration fee is $25. This fee includes a diskette
with all EZhelp executable files, a user's guide on the diskette,
Turbo C object libraries in all memory models, and documentation
on each function. When an update becomes available, registered
users will be notified. Updates will be be free for one year, less
media and postage costs. After one year, updates will be available
for half of the original registration fee.
Application developers:
The EZhelp object libraries, available to registered users, are
very economical. The total size required is less than 7k. Only one
function call is needed from your application to start EZhelp with
any of the options available with the command-line
version (EZHELP.EXE).
Fully-documented source code is available for Turbo C compilers
in the small memory model, and instructions on the few simple changes
needed to convert to other memory models. Source updates are also
available free of charge for 2 years, less media and postage costs.
Microsoft support will be available in the next version. Write if
you would like a notice.
To register EZhelp, print out a copy of the file "order.frm" with
this DOS command:
COPY ORDER.FRM > PRN
┌────────────────────────────────────────────────────────────────────┐
│ R e g i s t r a t i o n F o r m / U s e r P r o f i l e │
├────────────────────────────────────────────────────────────────────┤
│ Name Computer __________________ Brain Child Systems │
│ Company Application to use P.O. Box 3882 │
│ Address EZhelp (if any)____________ Austin, TX 78764 │
│ City State ZIP │
├────────────────────────────────────────────────────────────────────┤
│ │
│ Twenty percent of each registration fee will be donated to │
│ a non-profit, charitable organization. │
│ │
├──────────────────────────────┬─────────────────────────────────────┤
│ Basic │ Application developers: │
│ Registration fee...... 25.00 │ Source code ................ 25.00 │
│ Laser printed guide... 15.00 │ (excludes registration) │
└──────────────────────────────┴─────────────────────────────────────┘
{{ ---------------, 1,7,0 }}
{{ Charityware?, 1,8,0 }}
........................................................................
Charityware
─────────────────────
Twenty percent of each registration fee received for this
package will be donated to charity. This pledge extends for the
lifetime of this package and any subsequent versions.
The concept of charityware is something that should be
explored. This package is fundamentally a shareware package,
with voluntary registration and trial use. No obligation on
your part is implied with its use during a reasonable trial
period. The basic trust embedded in the shareware concept can
have a double benefit with the Charityware concept - not only
have you done your part to promote shareware and shareware
authors, you also have made a charitable contribution that
counts.
If you have any questions or comments on the Charityware
concept, please contact us. We have more information of
interest available to shareware authors and corporate donors.
........................................................................
{{ Forming outline, 2,1,0 }}
Forming an outline of the text
Writing an outline is the essential first step to creating
the reference. It will help to begin with the most general
subjects, and narrow the subjects into sub-topics and further
sub-topics. The outline itself should have no more than eight
levels of sub-topics.
A typical printed reference guide has a table of contents and
body of text, and an optional index. An EZHelp text file contains
the same elements. The items in the outline become topic definition
lines in the text. The text can be entered first, and the EZhelp
topic lines inserted later, or the topic lines can be entered first,
and the text inserted between them.
Topic lines include the name of the topic, the menu number,
the order within the menu, and sub-topics to follow, if applicable.
If there are no sub-topics to follow, the text following the topic
line will be displayed.
{{ Creating topics, 2,2,0 }}
Creating topics
Working from your outline, you will create Topic Descriptions
that will be displayed in the pop-up menus. The topic itself is
a line of text that you will insert in your document, just above
the point where the help text begins for that topic.
The topic consists of:
{{ topic name, menu #, menu order, next menu }}
{{ - double brackets placed in the text will begin
a topic definition. A topic definition is ended with
another set of brackets }}.
topic name - you may use up to fifteen characters for the
topic, beginning with the first character at the left.
menu # - this will identify the group of topics which
are to be shown on the same menu. The outermost menu,
or most general, should begin with 1 as a rule.
menu order - this will specify the order of the topic
among the other topics in the menu, from top to bottom.
If you wish the menu topics to be sorted alphabetically,
use 0 for the order number in each topic in the menu.
next menu - if this topic leads to another topic
sub-menu, use the sub-menu number. If this topic leads
to the help text (the help text follows the topic in the
document), use 0.
The topic which defined the text you are now reading is:
{{ Creating topics, 2,2,0 }}
Note that each parameter in the topic should be followed with
a comma. The spacing between the parameters is not critical,
but only numbers should be used for the last three. Menu numbers
may be 1 - 256, although the maximum number of menu layers is 16.
The topic definition must contain a complete set of brackets,
parameters, and commas, or unexpected results may occur.
Here is an example of a complete set of menu definitions for
a help reference describing methods of transportation:
{{ Land, 1, 1, 2 }}
{{ Water, 1, 2, 3 }} menu 1, 3 topics
{{ Air, 1, 3, 4 }} ____________________
{{ Car, 2, 1, 0 }}
{{ Bicycle, 2, 2, 0 }} menu 2, 3 topics
{{ Feet, 2, 3, 0 }} ____________________
{{ Speedboat, 3, 1, 0 }}
{{ Yacht, 3, 2, 0 }} menu 3, 3 topics
{{ Jet ski, 3, 3, 0 }} ____________________
{{ Airlines, 4, 1, 0 }}
{{ Hang glider, 4, 2, 0 }} menu 4, 2 topics
Note that menu in menu 1, topic "Land" defines a next menu, 2.
Also in menu 1, topic "Water" defines next menu 3, and topic
"Air" defines next menu 4.
{{ Entering text, 2,3,0 }}
Entering text
This is the basic layout of an EZhelp text file:
┌──────────────────────────┐
│ .beginning of file │
│ │
│ Comments (a) │ (a) Optional comments may be placed
│ │ at the beginning of the file, until
│ Topic definition (b) │ the first Topic definition.
│ │
│ Accompanying text (c) │ (b) A topic definition line will
│ │ always be followed with Accompanying
│ Topic definition (b) │ text unless another menu is to
│ │ follow.
│ Accompanying text (c) │
│ │ (c) The accompanying text will be
│ Topic definition (b) │ assumed to continue until the next
│ │ topic definition is found, or the
│ Accompanying text (c) │ end of the file is reached.
│ │
│ .end of file │
└──────────────────────────┘
An EZhelp text file MUST conform to these three guidelines:
1) Carriage return/line feed (CR/LF):
A carriage return/line feed pair must terminate every line in
the file. What this means for text written with many commercial
word processors (Microsoft Word, Wordperfect, others) is that it
will likely be neccessary to press the return key at the end of
each line, rather than letting the line wrap around.
One way to tell if your word processor generates the CR/LF at
the end of each line is to use the DOS "TYPE" command to view the
text file on the screen. If the text is not indented as you would
see it in the word processor, then you will need to press return
at the end of each line.
Avoid using the tab key in the text. Instead, indent using
the space bar. All other text formatting commands used by your
word processor should be avoided also. If it is possible, save
the file with your word processor in unformatted mode.
2) Line length:
A line MUST be 74 characters or less. If the line is longer
than 74 characters, unexpected results may occur. One common
result is when the entire page shifts up by one line. Take care
to follow this guideline.
3) Recompiling:
The reference text file must be recompiled after each time
it is modified. If it is not recompiled, the help text displays
will overlap, and the topic definition line may be visible on
the screen.
{{ Files involved, 3,1,0 }}
Files involved
"myfile.txt", when compiled, creates an index "myfile.hnx".
┌────────┐ ┌───────────────┐ ┌─────────┐
│ │ │ │ │ │
│ Text │ -----> │ EZcomp.exe │ -----> │ Text │
│ file │ -----> │ (compiler) │ -----> │ index │
│ │ │ │ │ │
└────────┘ └───────────────┘ └─────────┘
The index file name is created using the first part of the
text file name and adding ".hnx" as the extension. The index
file will be placed in the same subdirectory as the text file.
{{ Command line, 3,2,0 }}
Command line - EZcomp.exe
Usage: EZcomp MYFILE.TXT [-pu] [-ps]
From the DOS prompt, enter the following command to compile
a help text file:
EZcomp MYFILE.TXT
The compiler runs for a moment, creates the index "myfile.hnx"
using the text file "myfile.txt", and returns to the DOS prompt.
To compile the text and print an unsorted report of the topics,
enter this command:
EZcomp MYFILE.TXT -pu
To print a sorted report of the topics, substitute "-ps" on the
command line, or include both "-pu" and "-ps" for both reports.
{{ Reporting, 3,3,0 }}
Reporting
Shown below is a sample report generated by EZcomp.exe. The
report is printed once in the natural order that topic definitions
are found in the text, and once in the sorted order that is used
by EZhelp.exe.
----------------------------------------------------------------------
EZcomp v1.0 Reference Index report, unsorted: ezhelp.txt Page 1
----------------------------------------------------------------------
Menu Menu Next Line Line
number order Topic menu number count Offset Size
------ ----- --------------- ----- ------ ------ ------ ------
1 1 What's EZhelp? 8 91 244 2753
1 2 3 easy steps 99 22 3025 462
1 3 Writing text 2 121 4 3515 35
1 4 Compiling text 3 125 4 3578 35
1 5 Using EZhelp 4 129 4 3641 35
1 6 Registering 133 70 3704 2928
1 7 --------------- 203 2 6660 4
1 8 Charityware? 205 24 6692 1177
{{ Memory needed, 4,1,0 }}
Memory needed
EZhelp menus and help text windows allocate and release memory
as they are used. The amount of memory required will depend on the
size and levels of the menus. The program will have a pool of free
memory to use in the size of (64k - size of ezhelp.exe). If there
is no free memory to allocate, the program will display an error
message and exit.
As distributed here, EZHelp.exe was compiled in the small model
with Borland Turbo C. There are other memory models and compiled
versions available. For more information, see the topic
"Source code".
{{ Files involved, 4,2,0 }}
Files involved
┌───────────────┐ ┌────────┐
│ │ <----- │ Text │
│ │ <----- │ index │
│ EZhelp.exe │ └────────┘
│ (help text │
│ driver) │ ┌────────┐
│ │ <----- │ Text │
│ │ <----- │ file │
└───────────────┘ └────────┘
EZhelp.exe uses the text file created with a word processor or
text editor, and the index created from the text file with
EZcomp.exe, to drive the displays of menus and help text. If the
text file or text index is not found (as specified in the command
line), EZhelp will display an error message and exit.
{{ Command line, 4,3,0 }}
Command line - EZhelp.exe
Usage: EZhelp MYFILE.TXT [-Mnn -Jnn -Wnn -Bnn -Snn -Tnn -E ]
where...
MYFILE.TXT The name of a text reference file to be used. Up to
40 characters may be used for the full path and file
name. The index MYFILE.HNX is assumed to reside in
the same subdirectory.
-Mnn The number of the menu to start at. The program will
begin by displaying the Topic descriptions for that
menu, as defined in MYFILE.TXT. All subsequent menus
from the point of the startup menu will be accessible.
If none is specified, the default is 1.
-Jnn The number of the topic in the start menu specified
to display directly. If the -Jnn option is used, the
menu will not be shown, and the help text for topic
-Jnn in menu -Mnn will display.
-Wnn A number to define the color of the menu window borders,
non-highlighted menu items, and the help text display.
If a number is not specified, the default is 7, white.
-Bnn A number to define the color of the menu highlight bar.
The the default is 30, yellow on blue.
-Snn A number to define the size (in lines) of the help text
window display. The minimum window size is 4, and the
maximum is 23. The default is 23 lines.
-Tnn A number to define the menu and help text window
borders. The different styles available and their
numbers are show below. The default is 1.
┌───┐ ╒═══╕ ╔═══╗ ╓───╖ ▓▓▓▓▓ ▒▒▒▒▒ ░░░░░ ▄▄▄▄▄
│ 1 │ │ 2 │ ║ 3 ║ ║ 4 ║ ▓ 5 ▓ ▒ 6 ▒ ░ 7 ░ ▌ 8 ▐
└───┘ ╘═══╛ ╚═══╝ ╙───╜ ▓▓▓▓▓ ▒▒▒▒▒ ░░░░░ ▀▀▀▀▀
-E This option will turn error messages on. The default is
no error messages.
Examples:
1) EZhelp MYFILE.TXT
Start MYFILE.TXT at menu 1, use all defaults.
2) EZhelp MYFILE.TXT -M4 -J7 -S15
Jump directly to the display of topic 7 in menu 4. Use a
text display window of 15 lines.
3) EZhelp MYFILE.TXT -W1 -E
Start MYFILE.TXT at menu 1, using a window color of blue.
Turn error messages on.
Note: The order of the parameters is not critical.
{{ Examples, 4,3,90 }}
.... menu 90 is next ....
{{ Distribution, 4,5,0 }}
Distribution
Unregistered and registered users may distribute copies of this
package in its complete form, including EZhelp.exe, EZcomp.exe,
EZhelp.txt and EZhelp.hnx, and user's manual. We encourage you to
do so.
Registered users may bundle EZhelp.exe with their own
applications and distribute unlimited copies. If a registered
user distributes EZhelp.exe, the file name may not be changed.
For more information on registering EZhelp, select the
"Registering" topic.
{{ Source code, 4,6,0 }}
Source code
EZhelp source code is available for the Turbo C compiler in all
memory models, and the source code for EZcomp is also included.
For more information on obtaining source code, select the
"Registering" topic.
Only one function call is needed from your application to start
EZhelp with any of the options available with the command-line
version (EZHELP.EXE).
{{ Enhancments, 4,7,0 }}
Enhancements
Here is a list of enhancements that are being considered for
EZhelp. The ones with an asterisk next to them will be included
in version 1.1.
* Menu names at the top left of each menu
* Additional help window messages
* Single-letter menu selection
Front end with text editor
Help text printing
Single-line scrolling
If you have any suggestions for enhancements to this program,
send us a postcard or letter.
{{ ---------------, 4,8,0 }}
{{ Quick summary, 4,9,0 }}
Quick summary of commands
Topic definitions
─────────────────────────
{{ topic name, menu #, menu order, next menu }}
1 - 15 chars all of the 0 for sort on 0 for display
ended with a topics in topic name; text to follow;
comma a menu have Other - use Other - display
the same # order chosen the next menu
Compiling
─────────────────────────
EZcomp MYFILE.TXT [-pu] [-ps]
Note: Use your own help text file in place of MYFILE.TXT. Use
the -pu and -ps options to print a report on the text file
topics, unsorted or sorted.
Running EZhelp
─────────────────────────
EZhelp MYFILE.TXT [-Mnn -Jnn -Wnn -Bnn -Snn -Tnn -E ]
{{ 1 more menu, 90,0,91 }}
.... menu 91 is next ....
{{ 2 aaaaaaaaaaaa, 90,0,0 }}
{{ 3 aaaaaaaaaaaa, 90,0,0 }}
{{ 4 aaaaaaaaaaaa, 90,0,0 }}
{{ 5 aaaaaaaaaaaa, 90,0,0 }}
{{ 6 aaaaaaaaaaaa, 90,0,0 }}
{{ 7 aaaaaaaaaaaa, 90,0,0 }}
{{ 8 aaaaaaaaaaaa, 90,0,0 }}
{{ 9 aaaaaaaaaaaa, 90,0,0 }}
{{ 10 aaaaaaaaaaa, 90,0,0 }}
{{ 11 aaaaaaaaaaa, 90,0,0 }}
{{ 12 aaaaaaaaaaa, 90,0,0 }}
{{ 13 aaaaaaaaaaa, 90,0,0 }}
{{ 14 aaaaaaaaaaa, 90,0,0 }}
{{ 15 aaaaaaaaaaa, 90,0,0 }}
{{ 16 aaaaaaaaaaa, 90,0,0 }}
{{ 17 aaaaaaaaaaa, 90,0,0 }}
{{ 18 aaaaaaaaaaa, 90,0,0 }}
{{ 19 aaaaaaaaaaa, 90,0,0 }}
{{ 20 aaaaaaaaaaa, 90,0,0 }}
{{ 21 aaaaaaaaaaa, 90,0,0 }}
{{ 22 aaaaaaaaaaa, 90,0,0 }}
{{ 23 aaaaaaaaaaa, 90,0,0 }}
{{ 24 aaaaaaaaaaa, 90,0,0 }}
{{ 25 aaaaaaaaaaa, 90,0,0 }}
{{ 26 aaaaaaaaaaa, 90,0,0 }}
{{ 27 aaaaaaaaaaa, 90,0,0 }}
{{ 28 aaaaaaaaaaa, 90,0,0 }}
{{ 29 aaaaaaaaaaa, 90,0,0 }}
{{ 30 aaaaaaaaaaa, 90,0,0 }}
{{ 31 aaaaaaaaaaa, 90,0,0 }}
{{ 32 aaaaaaaaaaa, 90,0,0 }}
{{ 33 aaaaaaaaaaa, 90,0,0 }}
{{ 34 aaaaaaaaaaa, 90,0,0 }}
{{ 35 aaaaaaaaaaa, 90,0,0 }}
{{ 36 aaaaaaaaaaa, 90,0,0 }}
{{ 37 aaaaaaaaaaa, 90,0,0 }}
{{ 38 aaaaaaaaaaa, 90,0,0 }}
{{ 39 aaaaaaaaaaa, 90,0,0 }}
{{ 40 aaaaaaaaaaa, 90,0,0 }}
{{ 41 aaaaaaaaaaa, 90,0,0 }}
{{ 42 aaaaaaaaaaa, 90,0,0 }}
{{ 43 aaaaaaaaaaa, 90,0,0 }}
{{ 44 aaaaaaaaaaa, 90,0,0 }}
{{ 45 aaaaaaaaaaa, 90,0,0 }}
{{ 46 aaaaaaaaaaa, 90,0,0 }}
{{ 47 aaaaaaaaaaa, 90,0,0 }}
{{ 48 aaaaaaaaaaa, 90,0,0 }}
{{ 49 aaaaaaaaaaa, 90,0,0 }}
{{ 50 aaaaaaaaaaa, 90,0,0 }}
{{ 51 aaaaaaaaaaa, 90,0,0 }}
{{ 52 aaaaaaaaaaa, 90,0,0 }}
{{ 53 aaaaaaaaaaa, 90,0,0 }}
{{ 54 aaaaaaaaaaa, 90,0,0 }}
{{ 55 aaaaaaaaaaa, 90,0,0 }}
{{ 56 aaaaaaaaaaa, 90,0,0 }}
{{ 57 aaaaaaaaaaa, 90,0,0 }}
{{ 58 aaaaaaaaaaa, 90,0,0 }}
{{ 59 aaaaaaaaaaa, 90,0,0 }}
{{ 60 aaaaaaaaaaa, 90,0,0 }}
{{ 61 aaaaaaaaaaa, 90,0,0 }}
{{ 62 aaaaaaaaaaa, 90,0,0 }}
{{ 63 aaaaaaaaaaa, 90,0,0 }}
{{ 64 aaaaaaaaaaa, 90,0,0 }}
{{ 65 aaaaaaaaaaa, 90,0,0 }}
{{ 66 aaaaaaaaaaa, 90,0,0 }}
{{ 67 aaaaaaaaaaa, 90,0,0 }}
{{ 68 aaaaaaaaaaa, 90,0,0 }}
{{ 69 aaaaaaaaaaa, 90,0,0 }}
{{ 1 more menu, 91,0,92 }}
.... menu 92 is next ....
{{ 2 bbbbbbbbbbbb, 91,0,0 }}
{{ 3 bbbbbbbbbbbb, 91,0,0 }}
{{ 4 bbbbbbbbbbbb, 91,0,0 }}
{{ 5 bbbbbbbbbbbb, 91,0,0 }}
{{ 6 bbbbbbbbbbbb, 91,0,0 }}
{{ 7 bbbbbbbbbbbb, 91,0,0 }}
{{ 1 cccccccccccc, 92,0,0 }}
{{ 2 cccccccccccc, 92,0,0 }}
{{ 3 cccccccccccc, 92,0,0 }}
{{ 4 cccccccccccc, 92,0,0 }}
{{ 5 cccccccccccc, 92,0,0 }}
{{ 6 cccccccccccc, 92,0,0 }}
{{ 7 cccccccccccc, 92,0,0 }}
{{ 8 cccccccccccc, 92,0,0 }}
{{ 9 cccccccccccc, 92,0,0 }}
{{ 10 ccccccccccc, 92,0,0 }}
{{ 11 ccccccccccc, 92,0,0 }}
{{ 12 ccccccccccc, 92,0,0 }}
{{ 13 ccccccccccc, 92,0,0 }}
{{ 14 ccccccccccc, 92,0,0 }}
{{ 15 ccccccccccc, 92,0,0 }}
{{ 16 ccccccccccc, 92,0,0 }}
{{ 17 ccccccccccc, 92,0,0 }}
{{ 18 ccccccccccc, 92,0,0 }}
{{ 19 ccccccccccc, 92,0,0 }}
{{ 20 ccccccccccc, 92,0,0 }}
{{ 21 ccccccccccc, 92,0,0 }}
{{ 22 ccccccccccc, 92,0,0 }}
{{ 23 ccccccccccc, 92,0,0 }}
{{ 24 ccccccccccc, 92,0,0 }}
{{ 25 ccccccccccc, 92,0,0 }}
{{ 26 ccccccccccc, 92,0,0 }}
{{ 27 ccccccccccc, 92,0,0 }}
{{ 28 ccccccccccc, 92,0,0 }}
{{ 29 ccccccccccc, 92,0,0 }}
{{ 30 ccccccccccc, 92,0,0 }}
{{ 31 ccccccccccc, 92,0,0 }}
{{ 32 ccccccccccc, 92,0,0 }}
{{ 33 ccccccccccc, 92,0,0 }}
{{ 34 ccccccccccc, 92,0,0 }}
{{ 35 ccccccccccc, 92,0,0 }}